Documentation by viktorprogger · Pull Request #250 · yiisoft/queue

viktorprogger · 2025-12-13T10:21:35Z

Q	A
Is bugfix?	✔️
New feature?	❌
Breaks BC?	❌

codecov · 2025-12-13T13:20:23Z

Codecov Report

❌ Patch coverage is 97.72727% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 98.50%. Comparing base (4508fbe) to head (bb9bea8).

Files with missing lines	Patch %	Lines
src/Worker/Worker.php	92.85%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #250      +/-   ##
============================================
- Coverage     98.62%   98.50%   -0.13%     
+ Complexity      356      353       -3     
============================================
  Files            47       47              
  Lines           948      937      -11     
============================================
- Hits            935      923      -12     
- Misses           13       14       +1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

docs/guide/en/configuration-with-config.md

docs/guide/en/message-handler.md

README.md

Co-authored-by: Alexander Makarov <sam@rmcreative.ru>

…elated guides

Copilot

Pull request overview

This pull request is marked as a bugfix and includes significant documentation improvements, code refactoring, and a critical bug fix. The main changes involve integrating CallableFactory into the Worker class to simplify handler resolution, fixing a bug in the JSON message serializer, adding comprehensive documentation, and adding a command alias.

Key changes:

Integration of CallableFactory into Worker for unified callable resolution
Bug fix in JsonMessageSerializer where $payload['meta'] was incorrectly accessed instead of $meta
Extensive documentation added covering queue channels, message handlers, middleware pipelines, error handling, and more
Command alias queue:listen-all added to replace the typo queue:listen:all

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/Unit/WorkerTest.php	Added new test case for object method callable definitions and updated tests to use CallableFactory parameter
tests/Unit/Middleware/CallableFactoryTest.php	Major refactoring with data providers for comprehensive testing of callable factory scenarios
tests/TestCase.php	Added CallableFactory parameter to worker creation
tests/Integration/MiddlewareTest.php	Added CallableFactory parameter to test setup
tests/Integration/MessageConsumingTest.php	Added CallableFactory instantiation and parameter in worker setup
tests/Benchmark/QueueBench.php	Added CallableFactory parameter to worker constructor
src/Worker/Worker.php	Integrated CallableFactory for unified handler resolution, simplified handler caching logic
src/Middleware/CallableFactory.php	Enhanced to support Closure detection, object method definitions, and improved validation
src/Message/JsonMessageSerializer.php	Bug fix: corrected variable reference from `$payload['meta']` to `$meta`
src/Command/ListenAllCommand.php	Added command alias 'queue:listen:all' for backward compatibility
docs/guide/en/worker.md	Rewritten to focus on starting workers and supervisor configuration
docs/guide/en/usage.md	Expanded with queue channels, delayed execution, job status examples
docs/guide/en/producing-messages-from-external-systems.md	New comprehensive guide for external message producers
docs/guide/en/prerequisites-and-installation.md	New installation and requirements guide
docs/guide/en/middleware-pipelines.md	New detailed middleware pipeline documentation
docs/guide/en/message-handler.md	New guide explaining handler definition formats and configuration
docs/guide/en/loops.md	New documentation on loop interface and signal handling
docs/guide/en/job-status.md	New guide on job status tracking
docs/guide/en/error-handling.md	Significantly expanded with step-by-step failure handling flow
docs/guide/en/envelopes.md	New documentation on envelope pattern and metadata handling
docs/guide/en/debug-integration.md	New guide for Yii Debug integration
docs/guide/en/console-commands.md	New comprehensive console commands reference
docs/guide/en/configuration-with-config.md	New configuration guide for yiisoft/config users
docs/guide/en/configuration-manual.md	New manual configuration guide with examples
docs/guide/en/channels.md	New detailed guide on queue channels concept and configuration
docs/guide/en/callable-definitions-extended.md	New guide explaining extended callable definition formats
docs/guide/en/README.md	Restructured guide index with better organization
config/params.php	Added 'queue:listen-all' command alias
README.md	Major rewrite with quick start guide and improved structure

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/guide/en/callable-definitions-extended.md

README.md

docs/guide/en/producing-messages-from-external-systems.md

README.md

docs/guide/en/callable-definitions-extended.md

docs/guide/en/console-commands.md

docs/guide/en/debug-integration.md

samdark · 2026-01-07T20:35:05Z

docs/guide/en/error-handling.md

-## Configuration
+## When failure handling is triggered
+
+Failure handling is triggered only when message processing throws a `Throwable`.


How about PHP notices or warnings or errors?

docs/guide/en/error-handling.md

src/Worker/Worker.php

samdark · 2026-02-21T15:07:09Z

config/params.php

            'queue:run' => RunCommand::class,
            'queue:listen' => ListenCommand::class,
-            'queue:listen:all' => ListenAllCommand::class,
+            'queue:listen-all' => ListenAllCommand::class,


I think it was alright. The console works the best when the separator is :.

Copilot

Pull request overview

Copilot reviewed 38 out of 38 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-05T14:43:35Z

src/Worker/Worker.php

        $name = $message->getHandlerName();
-        $handler = $this->getHandler($name);
+        try {
+            $handler = $this->getHandler($name);
+        } catch (InvalidCallableConfigurationException $exception) {
+            throw new RuntimeException(sprintf('Queue handler with name "%s" does not exist.', $name), 0, $exception);
+        }
+
        if ($handler === null) {
            throw new RuntimeException(sprintf('Queue handler with name "%s" does not exist', $name));
        }


process() throws two different error messages for missing/invalid handler definitions: the InvalidCallableConfigurationException path ends with a period (... does not exist.) while the null handler path does not (... does not exist). This difference breaks tests that expect a stable message and makes error handling brittle. Consider using a single canonical message string for both paths (or update tests/BC accordingly).

Copilot · 2026-04-05T14:43:35Z

src/Command/RunCommand.php

        $this->addArgument(
            'channel',
            InputArgument::OPTIONAL | InputArgument::IS_ARRAY,
            'Queue channel name list to connect to.',
            $this->channels,
        )
            ->addOption(
-                'maximum',
+                'limit',
                'm',
                InputOption::VALUE_REQUIRED,
-                'Maximum number of messages to process in each channel. Default is 0 (no limits).',
+                'Number of messages to process in each channel. Default is 0 (no limits).',
                0,
            )
-            ->addUsage('[channel1 [channel2 [...]]] --maximum 100');
+            ->addUsage('[channel1 [channel2 [...]]] --limit 100');


The CLI option name was changed from --maximum to --limit. That is a backwards-incompatible change for anyone scripting this command, but the PR metadata says BC is not broken. Consider supporting --maximum as a deprecated alias (or documenting this as a BC break and updating release notes).

Copilot · 2026-04-05T14:43:35Z

src/Command/ListenAllCommand.php

            ->addOption(
                'pause',
                'p',
                InputOption::VALUE_REQUIRED,
                'Pause between queue channel iterations in seconds. May save some CPU. Default: 1',
                1,
            )
            ->addOption(
-                'maximum',
+                'limit',
                'm',
                InputOption::VALUE_REQUIRED,
-                'Maximum number of messages to process in each channel before switching to another channel. '
+                'Number of messages to process in each channel before switching to another channel. '
                    . 'Default is 0 (no limits).',
                0,
            );

-        $this->addUsage('[channel1 [channel2 [...]]] [--timeout=<timeout>] [--maximum=<maximum>]');
+        $this->addUsage('[channel1 [channel2 [...]]] [--pause=<pause>] [--limit=<limit>]');


The queue:listen-all command option was renamed from --maximum to --limit. This is a breaking CLI interface change (scripts/ops tooling will fail) while the PR metadata indicates no BC break. Consider keeping --maximum as an alias (possibly deprecated) or updating the PR metadata / changelog to reflect the breaking change.

Copilot · 2026-04-05T14:43:35Z

docs/guide/en/advanced-map.md

+- [Middleware pipelines deep dive](middleware-pipelines.md) — dispatcher lifecycle, request mutations, and per-pipeline contracts.
+- [Callable definitions and middleware factories](callable-definitions-extended.md) — container-aware definitions for middleware factories.
+- [Error handling](error-handling.md#failure-pipeline-overview) — end-to-end flow of the failure pipeline.
+- [Custom failure middleware](error-handling.md#how-to-create-a-custom-failure-middleware) — implementing `MiddlewareFailureInterface`.
+- [Envelope metadata and stack reconstruction](envelopes.md#metadata-and-envelope-stacking) — stack resolution and metadata merging.
+- [FailureEnvelope usage](error-handling.md#failureenvelope) — retry metadata semantics.
+- [Handler resolver pipeline](message-handler.md#resolver-pipeline) — alternative handler lookup strategies.
+
+## Queue adapters and interoperability
+
+- [Custom queue provider implementations](queue-names-advanced.md#extending-the-registry) — bespoke selection logic, tenant registries, and fallback strategies.
+- [Consuming messages from external systems](consuming-messages-from-external-systems.md) — contract for third-party producers.
+- [Adapter internals](adapter-list.md#available-adapters) — extend or swap backend adapters.
+
+## Tooling, diagnostics, and storage
+
+- [Yii Debug collector internals](debug-integration-advanced.md) — collector internals, proxies, and manual wiring.
+- [Job status storage extensions](job-status.md#extend-storage) — persisting custom metadata or drivers.
+- [Extending queue processes and supervisors](process-managers.md#custom-supervisors) — custom supervisor hooks and graceful shutdown integration.


Several anchors referenced here don’t exist in the target docs, so these links are currently broken on GitHub: error-handling.md#failure-pipeline-overview (heading is different), message-handler.md#resolver-pipeline, job-status.md#extend-storage, and process-managers.md#custom-supervisors. Please update the anchors (or add the missing sections) so the documentation map is navigable.

viktorprogger and others added 2 commits December 13, 2025 15:20

Start docs refining

745b353

Apply fixes from StyleCI

eb27a90

viktorprogger changed the title ~~Start docs refining~~ Documentation Dec 13, 2025

samdark reviewed Dec 14, 2025

View reviewed changes

viktorprogger and others added 13 commits December 18, 2025 08:58

Apply suggestions from code review

ac1a2f8

Co-authored-by: Alexander Makarov <sam@rmcreative.ru>

Update docs/guide/en/message-handler.md

1fb3057

Co-authored-by: Alexander Makarov <sam@rmcreative.ru>

Add links to mentioned packages

91bb7cf

Continue writing docs

2feaf14

Document Yii Debug integration

604f2c0

Fix queue:listen-all command name

aee4f72

Prerequisites and installation in the guide

7821be0

Middleware pipelines in the guide

4fe7321

Add comprehensive documentation for callable definitions and update r…

23e7997

…elated guides

Improve the channels.md guide

ae5867a

Remove redundant info from the main readme

f2e7eff

Guide improvements and bugfixes

c598caf

Merge two different failure handling guides

0f05e07

viktorprogger force-pushed the docs branch from bbc2707 to 0f05e07 Compare January 7, 2026 14:58

Apply Rector changes (CI)

dd3ae30

viktorprogger marked this pull request as ready for review January 7, 2026 15:19

samdark requested a review from Copilot January 7, 2026 19:50

Copilot started reviewing on behalf of samdark January 7, 2026 19:50 View session

Copilot AI reviewed Jan 7, 2026

View reviewed changes

samdark reviewed Jan 7, 2026

View reviewed changes

viktorprogger added 3 commits January 18, 2026 18:37

Rewrite channels doc

dd30d79

Improve channel docs and fix PR comments

a86b307

Fix docs due to PR comments

19c4c44

viktorprogger mentioned this pull request Feb 21, 2026

Divide queue and channel names #259

Merged

Merge branch 'master' into docs

011db93

viktorprogger and others added 3 commits February 21, 2026 14:30

Apply PHP CS Fixer and Rector changes (CI)

a189beb

Remove the old queue:listen:all command alias

a675bdc

Rename maximum console command parameter to the more common limit

da4a7a6

samdark reviewed Feb 21, 2026

View reviewed changes

viktorprogger added 2 commits February 21, 2026 21:52

Rename channels to queue names and generally improve docs

bb9bea8

Docs enhancements

108efce

samdark requested a review from Copilot April 5, 2026 14:38

Copilot started reviewing on behalf of samdark April 5, 2026 14:38 View session

Copilot AI reviewed Apr 5, 2026

View reviewed changes

Uh oh!

Conversation

viktorprogger commented Dec 13, 2025

Uh oh!

codecov bot commented Dec 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

samdark Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

samdark Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 5, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov bot commented Dec 13, 2025 •

edited

Loading